home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-13 / xvidoc.zip / SOURCE.MS < prev    next >
Text File  |  1992-07-28  |  44KB  |  1,414 lines
  1. .\"========== Redefine NH to avoid widowing
  2. .rn NH Nh
  3. .nr nH 0
  4. .de NH
  5. .br
  6. .if \\n(nH=\\$1 .sp 0.3i
  7. .nr nH 1
  8. .ne 1i
  9. .Nh \\$1 \\$2
  10. ..
  11. .\"========== Example macros
  12. .de Ex
  13. .br
  14. .ne 0.75i
  15. .IP "\fB\\$1\fP\ \ \ " \\$2
  16. ..
  17. .de Ey
  18. .sp -0.3v
  19. .IP "\fB\\$1\fP\ \ \ " \\$2
  20. ..
  21. .\"========== Put string in boldface & surround with quotes
  22. .de qB
  23. \%\*Q\fB\\$1\fP\*U\\$2
  24. ..
  25. .\"========== 11 on 13 looks so much better than 10 on 12
  26. .nr PS 11
  27. .nr VS 13
  28. .ps 11
  29. .vs 13p
  30. .nr PI 0.5i
  31. .nr HM 0.9i
  32. .nr FM 0.9i
  33. .if n .nr PO 0.5i
  34. .if n .nr LL 6.5i
  35. .\"========== Turn hyphenation off, and make sure it stays off
  36. .nh
  37. .rm hy
  38. .\"========== Headers in italics helps them to stand out from the text
  39. .OH '\fIXvi Source Code Notes\fP''\fI%\fP'
  40. .EH '\fI%\fP''\fIXvi Source Code Notes\fP'
  41. .OF '\fI25th September 1992\fP''\fIPage %\fP'
  42. .EF '\fIPage %\fP''\fI25th September 1992\fP'
  43. .\"===========================================================================
  44. .TL
  45. Notes on the Xvi Source Code
  46. .AU
  47. Chris Downey
  48. John Downey
  49. .AB no
  50. \fBXvi\fP (pronounced \fIecks-vee-eye\fP)
  51. is a free, portable, multi-window implementation of the popular
  52. .UX
  53. editor \fBvi\fP.
  54. .LP
  55. This document contains information on how
  56. to port \fBxvi\fP to systems not currently supported.
  57. It also explains
  58. how the \fBxvi\fP source code is arranged into modules,
  59. and explains some of the data structures which are used,
  60. so that modifications may be made if and when necessary
  61. to the editor itself.
  62. .AE
  63. .\"===========================================================================
  64. .NH 1
  65. INTRODUCTION
  66. .LP
  67. \fBXvi\fP is intended to be portable to just about any system.
  68. This is one of the central reasons for its existence; the
  69. authors wish to be able to use the same editor everywhere.
  70. .LP
  71. The main body of the editor is (supposedly) fully portable,
  72. relying only on standard facilities defined by the White
  73. Book, and on a set of \fIprimitives\fP which are provided by a set
  74. of one or more modules for each operating system.
  75. If
  76. .B __STDC__
  77. is defined, certain ANSI C facilities will be used,
  78. but the editor will compile with non-ANSI compilers.
  79. .LP
  80. Therefore, in order to port \fBxvi\fP to a new system, all that is
  81. necessary is to provide the defined set of \fIprimitives\fP, and
  82. then build the editor.
  83. Or at least, that's the idea; we have refined the set of primitives
  84. as we port the editor to new environments, and it's getting pretty easy now.
  85. .LP
  86. The rest of this document is divided into sections as follows:
  87. .IP "\fISection 2: System-Specific Modules\fP"
  88. This section deals with the layout of source files and makefiles
  89. which you will have to deal with when porting \fBxvi\fP.
  90. .IP "\fISection 3: Primitives Provided by xvi\fP"
  91. Discusses what primitives are provided by the main body of the editor source
  92. code for use by the system interface code.
  93. .IP "\fISection 4: System Interface\fP"
  94. Explains the primitives which need to be provided
  95. in order to make \fBxvi\fP work.
  96. .IP "\fISection 5: Data Structures\fP"
  97. Details the internal data types used in the editor,
  98. and any functions available for operating on those types.
  99. .IP "\fISection 6: Source Files\fP"
  100. Lists the source files comprising the editor,
  101. and explains what functionality is provided by each one.
  102. .\"===========================================================================
  103. .NH 1
  104. SYSTEM-SPECIFIC MODULES
  105. .LP
  106. The system-specific code normally consists of three (or more) files;
  107. a
  108. .qB .c
  109. file, a
  110. .qB .h
  111. file, and a makefile.
  112. For example:
  113. .DS
  114. .B
  115. qnx.c
  116. qnx.h
  117. makefile.qnx
  118. .R
  119. .DE
  120. comprise the system-specific module for the QNX operating system.
  121. .LP
  122. In most cases, the system-specific code is divided into two
  123. or more modules, where one (called the \fIsystem interface module\fP)
  124. is concerned with general interactions with the operating system
  125. and the other (called the \fIterminal interface module\fP)
  126. is designed for a specific interface to a display and keyboard
  127. (and possibly, a mouse).
  128. .LP
  129. For example, the generic
  130. .UX
  131. implementation has
  132. .B unix.c
  133. and
  134. .B unix.h
  135. for the system interface module, and
  136. .B termcap.c
  137. and
  138. .B termcap.h
  139. for the terminal interface module; this should
  140. work reasonably with any full-duplex terminal that can be
  141. described in the
  142. .B termcap
  143. database.
  144. On consoles with memory-mapped displays, or systems with graphic user
  145. interfaces, however, it may be possible to achieve faster
  146. display updating, and perhaps other benefits, by replacing
  147. the
  148. .B termcap
  149. module with another one that makes better use of
  150. whatever facilities are available.
  151. For instance, there is an experimental version for SunView,
  152. which allows mouse input on Sun workstations running the SunView window system.
  153. .LP
  154. On the other hand, the
  155. .B termcap -specific
  156. routines might
  157. conceivably be useful on some other operating systems (such
  158. as VMS), so in general it seemed a good idea to make the
  159. .B termcap -specific
  160. routines a separate module.
  161. .LP
  162. The current \%MS-DOS implementation has a separate terminal
  163. interface module, which is designed specifically for IBM PC
  164. compatible computers.
  165. This is in the files
  166. .DS
  167. .B
  168. ibmpc_a.asm
  169. ibmpc_c.c
  170. ibmpc.h
  171. .R
  172. .DE
  173. The first of these is written in assembly language because
  174. there are not enough routines common to the various \%MS-DOS
  175. C compilers which reliably access the display and keyboard at
  176. a low enough level.
  177. .LP
  178. The hardware-independent system interface module for \%MS-DOS is in
  179. .DS
  180. .B
  181. msdos_a.asm
  182. msdos_c.c
  183. msdos.h
  184. .R
  185. .DE
  186. The first of these is written in assembly
  187. language for the same reason as is
  188. .B ibmpc_a.asm .
  189. .LP
  190. Theoretically, different terminal interface modules could be
  191. written for \%MS-DOS systems running on hardware which is not
  192. IBM-compatible but, unfortunately, such systems seem to be
  193. virtually extinct nowadays.
  194. .LP
  195. Sometimes more than one makefile is provided, as in the case of
  196. .UX ,
  197. where different versions work in slightly different ways.
  198. .LP
  199. It is, of couse, not necessary to provide all \(em or any \(em
  200. of these files for a particular implementation; this is just a convention.
  201. The makefile(s) for each system determine what
  202. files are used in the compilation of the editor.
  203. .LP
  204. The following porting modules are available at present:
  205. .\" ----------------------------------------------------------
  206. .\" Note: this table does not fit very well with nroff output,
  207. .\" so please try to avoid widening it if you add anything.
  208. .TS
  209. center, box;
  210. c|c|c
  211. l|l|l.
  212. System    Makefile    Source Files
  213. _
  214. .sp 0.5v
  215. UNIX
  216.   BSD    \fBmakefile.bsd\fP    \fBunix.[ch] termcap.[ch]\fP
  217.   System V \fB\(dg\fP    \fBmakefile.usg\fP    \fBunix.[ch] termcap.[ch]\fP
  218.   AIX    \fBmakefile.aix\fP    \fBunix.[ch] termcap.[ch]\fP
  219.   ULTRIX    \fBmakefile.ult\fP    \fBunix.[ch] termcap.[ch]\fP
  220.   Xenix \fB\(dg\fP    \fBmakefile.xen\fP    \fBunix.[ch] termcap.[ch]\fP
  221.   POSIX (e.g. BSDI)    \fBmakefile.pos\fP    \fBunix.[ch] termcap.[ch]\fP
  222.   SunOS    \fBmakefile.sun\fP    \fBunix.[ch] termcap.[ch]\fP
  223.   SunView    \fBmakefile.sv\fP    \fBunix.[ch] sunview.h\fP
  224.         \fBsunfront.c sunback.c\fP
  225.         \fBxvi.icn\fP
  226. .sp 0.5v
  227. _
  228. .sp 0.5v
  229. \%MS-DOS        \fBmsdos_c.c msdos.h\fP
  230.         \fBibmpc_c.c ibmpc.h\fP
  231. .sp 0.5v
  232.   Microsoft C 5.*    \fBmakefile.msc\fP    \fB8086mm.inc ibmpc_a.asm\fP
  233.   & MASM 5.*        \fBmsdos_a.asm\fP
  234. .sp 0.5v
  235.   Microsoft Quick C    \fBmakefile.qc\fP    \fB8086mm.inc ibmpc_a.asm\fP
  236.   & MASM 5.*        \fBmsdos_a.asm\fP
  237. .sp 0.5v
  238.   Zortech C++ 2.*    \fBmakefile.zc2\fP    \fB8086mm.inc ibmpc_a.asm\fP
  239.   & MASM 5.*        \fBmsdos_a.asm\fP
  240. .sp 0.5v
  241.   Zortech C++ 3.*    \fBmakefile.zc3\fP    \fB8086mm.inc ibmpc_a.asm\fP
  242.   & MASM 5.*        \fBmsdos_a.asm\fP
  243. .sp 0.5v
  244.   Zortech C++ 3.*
  245.   386 protected mode    \fBmakefile.386\fP    \fBpc386.[ch]\fP
  246. .sp 0.5v
  247. _
  248. .sp 0.5v
  249. OS/2 \fB\(dg\fP
  250.   Version 1, text mode
  251.   Microsoft C 5.1    \fBmakefile.os2\fP    \fBos2vio.[ch]\fP
  252.   & MASM 5.1        \fBi286.asm\fP
  253. .sp 0.5v
  254. _
  255. .sp 0.5v
  256. QNX
  257.   Version 2/3 (CII)    \fBmakefile.qnx\fP    \fBqnx.[ch]\fP
  258.   Version 4 (Watcom C)    \fBmakefile.qn4\fP    \fBunix.[ch] termcap.[ch]\fP
  259. .sp 0.5v
  260. _
  261. .sp 0.5v
  262. TOS \fB\(dg\fP
  263.   Lattice C    \fBmakefile.tos\fP    \fBtos.[ch] tos.lnk\fP
  264. .sp 0.5v
  265. .TE
  266. .IP \fB\(dg\fP 2
  267. Versions marked with
  268. .B \(dg
  269. probably do not work, as systems
  270. have not been recently available to the authors for testing.
  271. .\"===========================================================================
  272. .NH 1
  273. PRIMITIVES PROVIDED BY XVI
  274. .NH 2
  275. General Definitions
  276. .LP
  277. The file
  278. .B xvi.h
  279. should be included by all system-specific modules;
  280. this file should also be edited
  281. so that a system-specific header
  282. file (or files), as determined by a predefined keyword,
  283. will be included.
  284. .LP
  285. For instance, under
  286. .UX ,
  287. the word
  288. .B UNIX
  289. is defined by passing the
  290. .B -DUNIX
  291. flag to the C compiler
  292. from the makefile, and
  293. .B xvi.h
  294. contains the following lines:
  295. .DS
  296. .B
  297. #ifdef UNIX
  298. #   include "unix.h"
  299. #endif
  300. .R
  301. .DE
  302. in order to obtain the
  303. .UX -related
  304. definitions from that header file.
  305. .LP
  306. Among the definitions in
  307. .B xvi.h
  308. are the following:
  309. .Ex bool_t
  310. A Boolean type having values
  311. .B TRUE
  312. or
  313. .B FALSE .
  314. .Ex const
  315. .Ey volatile
  316. These are defined out when
  317. .B __STDC__
  318. is not defined,
  319. so that it is always safe to use them.
  320. .LP
  321. .B xvi.h
  322. also includes various other header files which are needed.
  323. The following system header files are always included:
  324. .DS
  325. .B
  326. stdio.h
  327. ctype.h
  328. signal.h
  329. string.h
  330. .R
  331. .DE
  332. These files are included if
  333. .B __STDC__
  334. is defined:
  335. .DS
  336. .B
  337. stddef.h
  338. stdlib.h
  339. limits.h
  340. .R
  341. .DE
  342. and if
  343. .B __STDC__
  344. is not defined,
  345. .B xvi.h
  346. will provide its own
  347. definitions for the following:
  348. .DS
  349. .B
  350. INT_MAX
  351. INT_MIN
  352. ULONG_MAX
  353.  
  354. FILE    *fopen();
  355. char    *malloc();
  356. char    *getenv();
  357. .R
  358. .DE
  359. Finally, one of the following header files will be included:
  360. .DS
  361. .B
  362. stdarg.h
  363. varargs.h
  364. .R
  365. .DE
  366. depending on whether
  367. .B __STDC__
  368. is defined or not.
  369. In order to make coding of
  370. .B varargs
  371. functions easier, a macro
  372. .B VA_START ()
  373. is defined, which takes the same arguments as the
  374. ANSI-style
  375. .B va_start (),
  376. but which is also available in non-ANSI
  377. environments (e.g. BSD).
  378. .LP
  379. In order to make it possible to use ANSI-style prototypes
  380. for function declarations, but still allow compilation under
  381. non-ANSI environments, the following macro is provided:
  382. .DS
  383. .B
  384. #ifdef __STDC__
  385. #   define  P(args) args
  386. #else
  387. #   define  P()     ()
  388. #endif
  389. .R
  390. .DE
  391. so that function declarations may be specified thus:
  392. .DS
  393. .B
  394. extern FILE *fopen P((const char *, const char *));
  395. .R
  396. .DE
  397. Please use this facility when you provide declarations for
  398. your system primitives, unless your system always uses an
  399. ANSI compiler.
  400. .\"===========================================================================
  401. .NH 2
  402. Parameters
  403. .LP
  404. An important facility provided for use by system-specific
  405. modules is access to the editor's parameter table.
  406. This is achieved by means of some apparent functions,
  407. and a set of
  408. .B #define d
  409. token values.
  410. The functions are:
  411. .Ex "void set_param(int n, val)"
  412. This function sets the indicated parameter to the
  413. passed value, which must be of an appropriate type.
  414. Parameter values may be obtained by means of the following
  415. functions (actually macros):
  416. .Ex "char *Ps(int n)"
  417. return value of string parameter
  418. .Ex "int Pn(int n)"
  419. return value of numeric parameter
  420. .Ex "bool_t Pb(int n)"
  421. return value of boolean parameter
  422. .Ex "char **Pl(int n)"
  423. return value of list parameter (a
  424. \fBNULL\fP-terminated array of character pointers)
  425. .Ex "int Pen(int n)"
  426. return numeric value (index) of enumerated parameter
  427. .Ex "char **Pes(int n)"
  428. return string value of enumerated parameter
  429. .LP
  430. In all cases, the \fBint n\fP argument is the index of the parameter
  431. in the table; a set of
  432. .B #define s
  433. is provided, of the form:
  434. .DS
  435. .B P_name
  436. .DE
  437. which map the parameter names into integral values.
  438. Thus, for example, we might obtain the value of the
  439. .B colour
  440. parameter:
  441. .DS
  442. .B
  443. colour = Pn(P_colour);
  444. .R
  445. .DE
  446. or set the value of the
  447. .B helpfile
  448. parameter:
  449. .DS
  450. .B
  451. set_param(P_helpfile, "/usr/lib/xvi/help");
  452. .R
  453. .DE
  454. .\"===========================================================================
  455. .NH 1
  456. SYSTEM INTERFACE
  457. .NH 2
  458. Introduction
  459. .LP
  460. There follows a list of the primitives which must be provided
  461. either by the system interface module or by the underlying OS.
  462. Note that it is perfectly acceptable to implement functions or external
  463. variables as
  464. macros
  465. so long as they \*Qlook the same\*U as the definitions
  466. below.
  467. As a guideline, anything which is (a) in capitals, or (b) is a
  468. \fBconst\fP variable, will be implemented as a
  469. .B #define
  470. for most
  471. systems.
  472. .LP
  473. When you want to actually do the port, it is highly
  474. recommended that you copy the system-specific files for the
  475. system which seems closest to your own, and modify those
  476. files, rather than starting from scratch.
  477. .LP
  478. All the following symbols should be defined in the system
  479. interface module, or by standard header files already included
  480. by
  481. .B xvi.h ,
  482. or by other header files explicitly included by
  483. the system-specific header file:
  484. .\" ----- Standard items, not always available -----
  485. .Ex "const unsigned int MAXPATHLEN"
  486. The maximum number of characters in a pathname.
  487. .Ex "const unsigned int MAXNAMLEN"
  488. The maximum number of characters in a filename.
  489. .Ex "int remove(char *filename)"
  490. Remove the named file as per ANSI.
  491. .Ex "int rename(char *old, char *new)"
  492. Rename the file \fBold\fP to \fBnew\fP as per ANSI.
  493. .Ex "void sleep(unsigned int seconds)"
  494. Put the process to sleep for the given number of seconds.
  495. .\" ----- xvi specials -----
  496. .Ex "const char * const DIRSEPS"
  497. The pathname separators supported for system calls (e.g.
  498. \fB"\e\e\|/"\fP
  499. for \%MS-DOS).
  500. .Ex "FILE *fopenrb(char *file)"
  501. .Ey "FILE *fopenwb(char *file)"
  502. Like the standard
  503. .B fopen()
  504. library call,
  505. but they both open files in \*Qbinary\*U mode
  506. (i.e. no conversion of cr/lf/crlf is done),
  507. for reading and writing respectively.
  508. .Ex "bool_t exists(char *filename)"
  509. Returns
  510. .B TRUE
  511. if the named file exists.
  512. .Ex "bool_t can_write(char *filename)"
  513. Returns
  514. .B TRUE
  515. if the named file can be written,
  516. i.e. if a \fBfopenwb(filename)\fP will succeed.
  517. .Ex "char *fexpand(char *filename)"
  518. Returns a filename-expanded version of the passed filename.
  519. .Ex "#define SETVBUF_AVAIL"
  520. .Ey "const unsigned int READBUFSIZ"
  521. .Ey "const unsigned int WRTBUFSIZ"
  522. If
  523. .B SETVBUF_AVAIL
  524. (or
  525. .B __STDC__ )
  526. is defined, these constant values
  527. are used to set I/O buffer sizes (using the \fBsetvbuf()\fP function)
  528. for reading and writing files.
  529. Note that if buffers of these sizes are unavailable at runtime,
  530. the editor will try to allocate smaller buffers by iteratively
  531. halving the buffer size until the allocation succeeds.
  532. It is therefore acceptable for these values to be quite large.
  533. .Ex "char *tempfname(const char *filename)"
  534. Create a unique name for a temporary file,
  535. possibly using \fBfilename\fP as a base
  536. (this will be used by
  537. .B do_preserve()
  538. to create a backup file
  539. for the file named by
  540. .B filename ).
  541. The string returned must have been allocated using
  542. .B malloc() ;
  543. .B NULL
  544. can be returned if there is no more memory available.
  545. .Ex "int call_system(char *command)"
  546. Invoke the given command in a subshell.
  547. This is used for shell escapes from \fBxvi\fP.
  548. The command string may contain metacharacters
  549. which are expected to be expanded
  550. by a command interpreter, e.g.
  551. .UX
  552. .B /bin/sh ,
  553. \%MS-DOS
  554. .B command.com .
  555. Return value is 0 for success.
  556. In many environments, this call may safely be
  557. .B #define d
  558. as
  559. .B system(command) .
  560. .Ex "int call_shell(char *shell)"
  561. Invoke the named shell.
  562. This is used for the
  563. .B :shell
  564. command.
  565. It may be mapped into
  566. .B call_system() ,
  567. but is separate on some systems for
  568. efficiency reasons (i.e. not invoking two shells to get one).
  569. Return value is 0 for success.
  570. .Ex "bool_t"
  571. .Ey "sys_pipe(char *cmd, int (*wf)(FILE *), long (*rf)(FILE *))"
  572. Used for the
  573. .B !
  574. command.
  575. The first parameter is the command to invoke, while the second and third
  576. are functions which should be called with an open file pointer in order
  577. to
  578. write out old,
  579. or read in new
  580. lines (respectively).
  581. Note that if \*Qreal\*U pipes are not available, it is acceptable
  582. to implement this function using temporary files, but the \fBwf\fP
  583. function must obviously be called before \fBrf\fP.
  584. .Ex "void sys_exit(int code)"
  585. Exit with given exit status.
  586. This routine must not return.
  587. The editor is considered \*Qdead\*U once it has been called, and no
  588. further calls to editor functions should be made.
  589. .Ex "void delay(void)"
  590. Delay for a short time, about a fifth of a second.
  591. This is used for showing matching brackets when \fBshowmatch\fP is set.
  592. It is acceptable to just return if implementing this is not easy.
  593. .\"===========================================================================
  594. .NH 2
  595. Screen Control
  596. .LP
  597. An instance of the following structure must be defined
  598. in order to allow screen output to take place:
  599. .DS L
  600. .ta 1.3i 3i
  601. .B
  602.   typedef struct virtscr {
  603.     genptr    *pv_window;
  604.     int    pv_rows;
  605.     int    pv_cols;
  606. /* public: */
  607.     VirtScr    *(*v_new)(VirtScr *);
  608.     void    (*v_close)(VirtScr *);
  609.  
  610.     int    (*v_rows)(VirtScr *);
  611.     int    (*v_cols)(VirtScr *);
  612.  
  613.     void    (*v_clear_all)(VirtScr *);
  614.     void    (*v_clear_line)(VirtScr *);
  615.  
  616.     void    (*v_goto)(VirtScr *, int row, int col);
  617.     void    (*v_advise)(VirtScr *, int row, int col,
  618.         int index, char *str);
  619.  
  620.     void    (*v_write)(VirtScr *, int row, int col, char *str);
  621.     void    (*v_putc)(VirtScr *, int row, int col, int ch);
  622.  
  623.     void    (*v_set_colour)(VirtScr *, int colour);
  624.     int    (*v_colour_cost)(VirtScr *);
  625.  
  626.     void    (*v_flush)(VirtScr *);
  627.  
  628.     void    (*v_beep)(VirtScr *);
  629.  
  630. /* optional: not used if NULL */
  631.     void    (*v_insert)(VirtScr *, int row, int col, char *str);
  632.  
  633.     int    (*v_scroll)(VirtScr *, int start, int end, int nlines);
  634.   } VirtScr;
  635. .R
  636. .DE
  637. .LP
  638. The first three fields in this structure are \*Qprivate\*U, for use only
  639. within the implementation of the \*Qpublic\*U functions.
  640. The remaining fields are all function pointers, and are described below.
  641. Note that all functions have at least one parameter, which is a pointer
  642. to the instance of the \fBVirtScr\fP in question.
  643. This is always referred to as \fBvs\fP below.
  644. Note also that the top-left-hand corner of the window is taken to be (0,0).
  645. .Ex "v_new(vs)"
  646. Obtain a new \fBVirtScr\fP, and return a pointer to it.
  647. This is not used at present, and should return
  648. .B NULL .
  649. .Ex "v_close(vs)"
  650. Close the window to which \fBvs\fP refers.
  651. .Ex "v_rows(vs)"
  652. Return the number of rows in \fBvs\fP.
  653. .Ex "v_cols(vs)"
  654. Return the number of columns in \fBvs\fP.
  655. .Ex "v_clear_all(vs)"
  656. Clear the window completely.
  657. .Ex "v_clear_line(vs, int row, int col)"
  658. Clear the specified line, from the given column to the right hand edge
  659. of the window, inclusive.
  660. .Ex "v_goto(vs, int row, int col)"
  661. Move the cursor to the specified row and column.
  662. .Ex "v_advise(vs, int row, int col, int index, char *str)"
  663. This function is called when the editor is about to produce some
  664. output on the same line as the last output, but separate from it
  665. by one or more characters.
  666. The destination position is the coordinate pair \fB(row, col + index)\fP,
  667. and \fBstr\fP contains the string of characters which are in the window
  668. starting at position \fB(row, col)\fP.
  669. Where there is a cost incurred
  670. by moving the cursor to a specific screen position,
  671. the terminal interface module may decide to write the intervening characters
  672. to the screen rather than using a specific \*Qmove cursor\*U sequence,
  673. in order to minimise the number of characters written to the terminal.
  674. .Ex
  675. Note that for many environments, the cost of re-positioning the cursor is
  676. nil, and under these circumstances this function need not do anything.
  677. .Ex "v_write(vs, int row, int col, char *str)"
  678. Write the specified string of characters into the window, starting at
  679. the specified row and column.
  680. The parameters will be such that the string will always fit into
  681. a single line of the window, i.e. no line-wrapping is necessary;
  682. however, it is quite possible for the string to end on the last character
  683. of a line, and some implementations will need to take special
  684. precautions to handle this correctly.
  685. .Ex "v_putc(vs, int row, int col, int ch)"
  686. This is like \fBv_write\fP but for a single character.
  687. .Ex "v_set_colour(vs, int colour)"
  688. Set the colour for all subsequent output (including clearing of
  689. lines or the whole window) to the specified colour.
  690. The meaning of the value is system-specific.
  691. .Ex "v_colour_cost(vs)"
  692. Return the number of extra characters which are taken up in the window
  693. by a colour change.
  694. This is almost always 0,
  695. but there exist some terminals for which it is not
  696. (see the
  697. .qB sg
  698. .B termcap
  699. capability).
  700. .Ex "v_flush(vs)"
  701. Flush all screen output, and move the cursor on the screen to the correct
  702. position.
  703. The screen need not actually be updated until either this function is called,
  704. or \fBxvi_handle_event()\fP returns.
  705. .Ex "v_beep(vs)"
  706. Beep.
  707. It is acceptable to flash the screen or window if no audio facility
  708. is available.
  709. .Ex "v_insert(vs, int row, int col, char *str)"
  710. This function inserts the given string at the given position,
  711. pushing any other characters on the same row to the right.
  712. If such a facility is not available,
  713. the function pointer should be set to
  714. .B NULL .
  715. .Ex "v_scroll(vs, int start, int end, int nlines)"
  716. This function scrolls the set of lines between \fBstart\fP and \fBend\fP
  717. (inclusive) by \fBnlines\fP lines.
  718. If \fBnlines\fP is positive, \fInormal\fP scrolling should be done,
  719. i.e. the lines should be moved upwards with respect to the window.
  720. If \fBnlines\fP is negative, scrolling should be in the reverse direction.
  721. The lines which are left by the scrolling should be cleared.
  722. The function should return non-zero if the scrolling was successful,
  723. otherwise 0.
  724. .Ex
  725. If scrolling is not available, the function pointer should be set to
  726. .B NULL .
  727. .\"===========================================================================
  728. .NH 2
  729. Parameters
  730. .LP
  731. Default values should be
  732. .B #define d
  733. for certain parameters
  734. as follows:
  735. .TS
  736. center, box;
  737. c|c|c
  738. l|c|l.
  739. Parameter Name    Type    \fB#define\fP name
  740. _
  741. \fBsyscolour\fP    numeric    \fBDEF_SYSCOLOUR\fP
  742. \fBcolour\fP    numeric    \fBDEF_COLOUR\fP
  743. \fBstatuscolour\fP    numeric    \fBDEF_STCOLOUR\fP
  744. \fBroscolour\fP    numeric    \fBDEF_ROSCOLOUR\fP
  745. \fBhelpfile\fP    string    \fBHELPFILE\fP
  746. \fBformat\fP    string    \fBDEF_TFF\fP
  747. .TE
  748. .\===========================================================================
  749. .NH 2
  750. File Formats
  751. .LP
  752. The functions in \fBxvi\fP which read and write text
  753. files are aware of several different newline conventions
  754. (for example,
  755. \fB"\e\^n"\fP on
  756. .UX ,
  757. \fB"\e\^r\^\e\^n"\fP on \%MS-DOS, and so on), so
  758. that any version of the editor can read and write any of the
  759. supported formats.
  760. The value of the \fBformat\fP parameter
  761. (which can be set to
  762. .qB unix ,
  763. .qB msdos ,
  764. .qB macintosh ,
  765. etc.)
  766. determines which format is currently being used.
  767. If you are porting \fBxvi\fP to a system with a newline convention which
  768. isn't one of those currently supported (see the table called
  769. .B tftable
  770. in
  771. .B fileio.c )
  772. you may have to add a new entry to the table.
  773. .LP
  774. Unfortunately, the current design is not as general as it ought to be.
  775. If you happen to be porting to VMS,
  776. or some other system which doesn't use either
  777. a single character
  778. or a consecutive pair of characters
  779. to represent a newline,
  780. you will have quite a lot of work to do
  781. if you want to retain the facility for
  782. converting between file formats within the editor.
  783. .LP
  784. In any case, your system interface module should define
  785. .B DEF_TFF
  786. to be the index of the entry in \fBtftable\fP
  787. which represents the default format for your system.
  788. This is the value for
  789. .B Pen(P_format)
  790. which will be
  791. compiled into the parameter table.
  792. .\"===========================================================================
  793. .NH 2
  794. Notes on Termcap Implementation
  795. .LP
  796. There exists a \fBtermcap\fP implementation of the terminal interface,
  797. currently only used for the
  798. .UX
  799. port.
  800. This module could quite easily be re-used for other systems if desired;
  801. the following routines would need to be defined by the system module:
  802. .Ex "void foutch(int c)"
  803. Output a single character to the terminal.
  804. This must be implemented as a function, not a macro, because it is passed
  805. as a parameter into the
  806. .B termcap
  807. library.
  808. .Ex "void moutch(int c)"
  809. Same as
  810. .B foutch()
  811. except that it can be implemented as a macro.
  812. This will be used by the
  813. .B termcap
  814. interface module to write characters to
  815. the screen.
  816. .Ex "void oflush(void)"
  817. Flush buffered output to the terminal.
  818. .\"===========================================================================
  819. .NH 2
  820. Entering/Leaving Visual Mode
  821. .LP
  822. Some facility is commonly necessary for the system interface module
  823. to be able to tell the terminal interface module to enter or exit
  824. \fIvisual\fP mode.
  825. This might mean changing the terminal state between \*Qraw\*U and \*Qcooked\*U
  826. modes, or switching display pages.
  827. No specific interface for this is defined,
  828. although the standard
  829. .UX
  830. and \%MS-DOS implementations do use such a facility,
  831. and the interface functions for both systems are identically defined.
  832. .\"===========================================================================
  833. .NH 2
  834. Function Keys\|\|/\|\|Mouse Handling
  835. .LP
  836. Function key values are coded into a set of
  837. .B #define d
  838. constants in the file
  839. .B ascii.h ;
  840. e.g. the value
  841. .B K_UARROW
  842. might be given as input when the keyboard up-arrow key has been pressed.
  843. .LP
  844. If the global variable
  845. .B State
  846. is not equal to
  847. .B NORMAL ,
  848. all
  849. function keys except for a backspace key are invalid input.
  850. If an invalid key is pressed, the safest strategy may be to
  851. beep and wait for another key to be pressed.
  852. .B NORMAL
  853. is defined in
  854. .B xvi.h .
  855. .LP
  856. Another facility which may be provided
  857. is handling mouse input on systems where it is available.
  858. The strategy for interpreting mouse input is controlled
  859. by the
  860. .B mouseclick()
  861. function (in
  862. .B mouse.c );
  863. the idea is
  864. to make the strategy independent of any specific device interface.
  865. If a mouse button is pressed before a keyboard key is pressed,
  866. the following routine should be called:
  867. .DS
  868. .B "mouseclick(int row, int column);"
  869. .DE
  870. where row and column are the current co-ordinates, counted
  871. in character positions, of the mouse pointer within the
  872. screen or editing window.
  873. If the mouse is moved while a button is held down, the routine
  874. .DS
  875. .B "mousedrag(int startrow, int endrow, int startcolumn, int endcolumn);"
  876. .DE
  877. should be called with co-ordinates describing the movement.
  878. If the global variable
  879. .B State
  880. is not equal to
  881. .B NORMAL ,
  882. mouse input can be ignored altogether.
  883. .LP
  884. All this will be considerably tidied up at a later stage, when we have
  885. proper
  886. .B xvEvent
  887. types for function keys and mouse actions.
  888. .\"===========================================================================
  889. .NH 2
  890. Main
  891. .LP
  892. Finally, the system interface module must provide a \fBmain()\fP function.
  893. This function must call \fBxvi_startup(vs, argc, argv, env)\fP at startup,
  894. with parameters as follows:
  895. .Ex "VirstScr *vs;"
  896. This is a pointer to the \fBVirtScr\fP structure for the first window,
  897. or for the terminal screen.
  898. .Ex "int argc, char **argv;"
  899. These are as for a \fBmain()\fP function.
  900. .Ex "char *env;"
  901. This is an environment string, normally the return value from
  902. \fBgetenv("XVINIT")\fP.
  903. If the concept of environment variables does not exist,
  904. a string of the form \fB"source\ \fIfilename\fB"\fR may be passed instead,
  905. so as to allow users to localise their usage of the editor.
  906. .LP
  907. The return value from \fBxvi_startup()\fP is a pointer, which will
  908. be used in future to identify the window for input events.
  909. For now, it should be stored in the \fBVirtScr\fP's \fBpv_window\fP field.
  910. .LP
  911. Having called \fBxvi_startup()\fP, input events may then be passed
  912. to the editor by calling \fBxvi_handle_event\fP with a pointer to
  913. an \fBxvEvent\fP structure as the sole argument.
  914. This structure is defined as follows:
  915. .DS
  916. .B
  917. typedef struct event {
  918.     enum {
  919.         Ev_char,
  920.         Ev_timeout
  921.     }                   ev_type;
  922.     union {
  923.         /* Ev_char: */
  924.         int evu_inchar;
  925.  
  926.         /* Ev_timeout: */
  927.     }                   ev_u;
  928. } xvEvent;
  929.  
  930. #define    ev_inchar    ev_u.evu_inchar
  931. .R
  932. .DE
  933. .LP
  934. The \fBev_type\fP field is a tag which identifies the type of event
  935. which has occurred.
  936. At present, only two events are supported: an input character from
  937. the user, and a timeout.
  938. The union which follows contains data associated with each event type;
  939. currently only the type \fBEv_char\fP requires data, as may be seen.
  940. The
  941. .B #define
  942. for \fBev_inchar\fP is provided purely for convenience.
  943. .LP
  944. The return value from \fBxvi_handle_event()\fP is a long integer value
  945. which is the time in milliseconds for which the editor is prepared
  946. to wait for more input.
  947. If no input arrives within that time, the function should be called
  948. again with an event of type \fBEv_timeout\fP.
  949. The timeout value returned may be 0L, indicating that no timeout is necessary.
  950. It is very important that timeouts should actually be implemented because
  951. they are needed for the
  952. .B preserve
  953. facility.
  954. .LP
  955. Currently, if a keyboard interrupt is received,
  956. .B xvi_handle_event()
  957. need not be called
  958. (it should,
  959. in any case,
  960. never be called from an asynchronous interrupt
  961. or signal
  962. handler)
  963. but the global variable
  964. .B kbdintr
  965. should be set to a non-zero value.
  966. .\"===========================================================================
  967. .NH 1
  968. DATA STRUCTURES
  969. .LP
  970. Structures used in \fBxvi\fP are all typedef'd,
  971. and all begin with a capital letter.
  972. They are defined in
  973. .B xvi.h .
  974. The following data structures are defined:
  975. .NH 2
  976. Line
  977. .LP
  978. This structure is used to hold a single text line.
  979. It contains forward and backward pointers which are connected together
  980. to form a two-way linked list.
  981. It also contains a pointer to an allocated text buffer,
  982. an integer recording the number of bytes allocated for the text,
  983. and the line number (an unsigned long).
  984. The text is null-terminated, and the space allocated for it may be
  985. grown but is never shrunk.
  986. The maximum size of this space is given by
  987. .B MAX_LINE_LENGTH .
  988. .LP
  989. The line number is used when showing line numbers on screen, but this
  990. is secondary to its main purpose of providing an ordering on lines;
  991. the ordering of two lines in a list may be established by simply
  992. comparing their line numbers
  993. (macros are available for this purpose; see later for details).
  994. .NH 2
  995. Buffer
  996. .LP
  997. This structure holds the internal representation of a file.
  998. It contains pointers to the
  999. linked list of lines which comprise the actual text.
  1000. We always allocate an extra line at the beginning and the end,
  1001. with line numbers 0 and
  1002. .B MAX_LINENO
  1003. respectively,
  1004. in order to make the code which deals with this structure easier.
  1005. The line numbers of \fBLine\fP structures in a \fBBuffer\fP
  1006. are always maintained by code in \fBundo.c\fP,
  1007. which is the only module which ever changes the text of a \fBBuffer\fP.
  1008. .LP
  1009. The \fBBuffer\fP structure also contains:
  1010. .IP \(bu
  1011. flags, including readonly and modified
  1012. .IP \(bu
  1013. current filename associated with the buffer
  1014. .IP \(bu
  1015. temporary filename for buffer preservation
  1016. .IP \(bu
  1017. space for the
  1018. .B mark
  1019. module to store information about marked lines
  1020. .IP \(bu
  1021. space for the
  1022. .B undo
  1023. module to store information about the last change
  1024. .IP \(bu
  1025. number of windows associated with the buffer
  1026. .LP
  1027. The following macros are used to find out certain information
  1028. about \fBLine\fPs within \fBBuffers\fP:
  1029. .Ex "lineno(Buffer *b, Line *l)"
  1030. Returns the line number of the specified \fBLine\fP,
  1031. which belongs to the specified \fBBuffer\fP.
  1032. .Ex "earlier(Line *l1, Line *l2)"
  1033. Returns
  1034. .B TRUE
  1035. if \fBl1\fP is earlier in the buffer than \fBl2\fP.
  1036. .Ex "later(Line *l1, Line *l2)"
  1037. Returns
  1038. .B TRUE
  1039. if \fBl1\fP is later in the buffer than \fBl2\fP.
  1040. .Ex "is_lastline(Line *l1)"
  1041. Returns
  1042. .B TRUE
  1043. if \fBl1\fP is the last line (i.e. the extra line
  1044. at the end, not the last text line) of the buffer.
  1045. .Ex "is_line0(Line *l1)"
  1046. Returns
  1047. .B TRUE
  1048. if \fBl1\fP is the 0th line (i.e. the extra line
  1049. at the start, not the first text line) of the buffer.
  1050. .NH 2
  1051. Posn
  1052. .LP
  1053. This structure is very simple; it contains a \fBLine\fP pointer and an integer
  1054. index into the line's text, and is used to record a position within a buffer,
  1055. e.g. the current cursor position.
  1056. .LP
  1057. These functions are available for operating on \fBPosn\fP structures:
  1058. .Ex "gchar(Posn *)"
  1059. Returns the character which is at the given position.
  1060. .Ex "inc(Posn *)"
  1061. Increments the given position, moving past
  1062. end-of-line to the next line if necessary.
  1063. The following type is returned:
  1064. .DS L
  1065. .B
  1066. .ta 2i
  1067.   enum mvtype {
  1068.       mv_NOMOVE,    /* at beginning or end of buffer */
  1069.       mv_SAMELINE,    /* still within same line */
  1070.       mv_CHLINE,    /* changed to different line */
  1071.       mv_EOL,    /* at terminating '\e0' */
  1072.   };
  1073. .R
  1074. .DE
  1075. .Ex "dec(Posn *)"
  1076. As for \fBinc()\fP but decrements the position.
  1077. .Ex "lt(Posn *p1, Posn *p2)"
  1078. Returns
  1079. .B TRUE
  1080. if the position specified by \fBp1\fP is earlier in the buffer
  1081. than that specified by \fBp2\fP.
  1082. .NH 2
  1083. Xviwin
  1084. .LP
  1085. This structure maps a screen window onto a \fBBuffer\fP.
  1086. It contains:
  1087. .IP \(bu
  1088. a pointer to the \fBBuffer\fP structure which it is mapped onto
  1089. .IP \(bu
  1090. the cursor's \fIlogical\fP position in the buffer (a \fBPosn\fP structure)
  1091. .IP \(bu
  1092. the cursor's \fIphysical\fP position in the window (row and column)
  1093. .IP \(bu
  1094. information about size and location of screen window
  1095. .IP \(bu
  1096. current text of status line
  1097. .IP \(bu
  1098. forward and backward pointers to other windows
  1099. .LP
  1100. Note that there is at least one \fBXviwin\fP for every \fBBuffer\fP.
  1101. .LP
  1102. When the editor was modified to support buffer windows, many
  1103. global variables were moved into the \fBBuffer\fP and \fBXviwin\fP structures;
  1104. some were left as globals.
  1105. For instance, the
  1106. .I undo
  1107. and
  1108. .I mark
  1109. facilities are obviously buffer-related,
  1110. but
  1111. .I yank
  1112. is useful if it is global
  1113. (actually static within its own module);
  1114. it was decided that
  1115. .I search
  1116. and
  1117. .I redo
  1118. should also be global.
  1119. .LP
  1120. Some modules have their own internal static data structures;
  1121. for instance, the
  1122. .B search
  1123. module remembers the last pattern
  1124. searched for.
  1125. Also, certain modules use data structures which are included
  1126. in more global ones; e.g. each \fBBuffer\fP structure contains some
  1127. data used only within
  1128. .B undo.c .
  1129. This is not very well structured, but in practice it's quite
  1130. clean because we simply ensure that references to such structures
  1131. are kept local to the module which \*Qowns\*U them.
  1132. .NH 2
  1133. Mark
  1134. .LP
  1135. This data structure records a mark (defined by the \fBm\fP command).
  1136. It contains a \fBPosn\fP and a character field to hold the letter
  1137. which defines the mark.
  1138. Each \fBBuffer\fP contains an array of these structures for holding
  1139. alphabetic marks, plus one for the previous context mark
  1140. (as used by the
  1141. .B ''
  1142. and
  1143. .B ``
  1144. commands).
  1145. The file
  1146. .B mark.c
  1147. deals with marks.
  1148. .NH 2
  1149. Change
  1150. .LP
  1151. This structure records a single change which has been made to a buffer.
  1152. It also contains a pointer, so that it may be formed into a list.
  1153. See the discussion of
  1154. .B undo.c
  1155. below for further details.
  1156. .NH 2
  1157. Flexbuf
  1158. .LP
  1159. This structure is used to store text strings for which the length is unknown.
  1160. The following operations are defined for this type.
  1161. All functions take a Flexbuf pointer as a parameter.
  1162. .Ex "flexnew(f)"
  1163. Initialise a Flexbuf; not needed for static Flexbufs.
  1164. .Ex "flexclear(f)"
  1165. Truncate a Flexbuf to zero length, but don't free its storage.
  1166. .Ex "flexdelete(f)"
  1167. Free all storage belonging to a Flexbuf.
  1168. .Ex "flexempty(f)"
  1169. Return
  1170. .B TRUE
  1171. if the Flexbuf is empty.
  1172. .Ex "flexlen(f)"
  1173. Return the number of characters in the Flexbuf.
  1174. .Ex "flexrmchar(f)"
  1175. Remove the last character from a Flexbuf.
  1176. .Ex "flexpopch(f)"
  1177. Remove the first character from a Flexbuf and return it.
  1178. .Ex "flexgetstr(f)"
  1179. Return a pointer to the string contained in the Flexbuf.
  1180. .Ex "flexaddch(f, c)"
  1181. Add the character \fBc\fP to the end of the Flexbuf.
  1182. .Ex "lformat(f, fmt, ...)"
  1183. A subset of \fBsprintf()\fP but for Flexbufs.
  1184. .Ex "vformat(f, fmt, va_list)"
  1185. A subset of \fBvsprintf()\fP but for Flexbufs.
  1186. .LP
  1187. The last two functions are especially useful, since they avoid
  1188. the usual problems with the lack of bounds-checking in \fBsprintf()\fP.
  1189. All code in the editor itself now uses Flexbufs to avoid the possibility
  1190. of buffer overruns, and to reduce the size of the executable.
  1191. Some OS-specific modules, however, may still use the \fBprintf()\fP family.
  1192. The subset of \fBprintf\fP-like format specifiers implemented includes
  1193. those for integers and strings, but not for floating-point numbers.
  1194. .NH 2
  1195. bool_t
  1196. .LP
  1197. A simple Boolean type; has values
  1198. .B TRUE
  1199. and
  1200. .B FALSE ,
  1201. which are defined as
  1202. 1 and 0 so as to be compatible with C comparison operators.
  1203. .NH 2
  1204. xvEvent
  1205. .LP
  1206. This type is defined in the previous section,
  1207. since it forms part of the porting interface.
  1208. .NH 2
  1209. VirtScr
  1210. .LP
  1211. This type represents a virtual screen, and
  1212. is constructed in a similar way to a \fIclass\fP.
  1213. It contains some function pointers which may be used to manipulate the
  1214. screen in various ways, and some private data which is used by the
  1215. implementation of the class.
  1216. .LP
  1217. The old terminal interface, which consisted of a set of disparate functions,
  1218. is being replaced by the \fBVirtScr\fP interface;
  1219. the first step in this process has been accomplished
  1220. by the provision of a default \fBVirtScr\fP implementation
  1221. using the old primitive functions.
  1222. New, native, \fBVirtScr\fP implementations may now be coded,
  1223. which will increase the efficiency of screen output.
  1224. .LP
  1225. As the final stage, a windowing implementation of the \fBVirtScr\fP class
  1226. will be provided, using the underlying \fBVirtScr\fP implementations,
  1227. and the window-handling code in the editor will be modified to
  1228. that each occurrence of an \fBXviwin\fP references its own \fBVirtScr\fP.
  1229. It will then be possible to build a version of the editor which operates in a
  1230. true windowing environment by using a separate screen window for each buffer,
  1231. instead of the current vertical-split method.
  1232. .LP
  1233. A full definition of the \fBVirtScr\fP type will be found
  1234. in the previous section.
  1235. .\"===========================================================================
  1236. .NH 2
  1237. Global Variables
  1238. .LP
  1239. There are only a few global variables in the editor.
  1240. These are the important ones:
  1241. .Ex curbuf 0.7i
  1242. pointer to the current \fBBuffer\fP
  1243. .Ex curwin 0.7i
  1244. pointer to the current \fBXviwin\fP
  1245. .Ex State 0.7i
  1246. the current \fIstate\fP of the editor;
  1247. controls what we do with input characters.
  1248. The value is one of the following:
  1249. .RS
  1250. .Ex NORMAL 1i
  1251. The default state; \fBvi\fP-mode commands may be executed
  1252. .Ex INSERT 1i
  1253. Insert mode, i.e. characters typed get inserted into the current buffer
  1254. .Ex REPLACE 1i
  1255. Replace mode, characters in the buffer get overwritten by what is typed
  1256. .Ex CMDLINE 1i
  1257. Reading a colon-command, regular expression or pipe command
  1258. .Ex DISPLAY 1i
  1259. Displaying text, i.e. \fB:p\fP command, or \fB:set\fP or \fB:map\fP with no argument
  1260. .RE
  1261. .Ex echo 0.7i
  1262. This variable controls what output is currently displayable.
  1263. It is used at various points within the editor to stop certain
  1264. output which is either undesirable or sub-optimal.
  1265. It must always
  1266. be restored to its previous value after the code which changed it
  1267. has finished what it is doing.
  1268. .Ex kbdintr 0.7i
  1269. This can be set to a non-zero value to indicate that an asynchronous
  1270. user-generated interrupt (such as a keyboard interrupt) has occurred.
  1271. See the discussion of event handling in the previous section.
  1272. .\"===========================================================================
  1273. .nr PI 1i    \" Extra indentation for filenames
  1274. .NH 1
  1275. SOURCE FILES
  1276. .LP
  1277. The header file
  1278. .B xvi.h
  1279. contains all the type definitions
  1280. used within the editor, as well as function declarations etc.
  1281. .LP
  1282. The following source files form the primary interface to the editor:
  1283. .Ex startup.c
  1284. Entry point for the editor.
  1285. Deals with argument
  1286. and option parsing and initial setup, calling
  1287. module initialisation functions as necessary.
  1288. .Ex events.c
  1289. Contains the routine \fBxvi_handle_event()\fP, which is
  1290. the entry point for handling input to the editor;
  1291. input is passed to different routines according to the
  1292. \fBState\fP variable.
  1293. Timeouts on input are also handled here, by calling appropriate
  1294. routines in \fBmap.c\fP or \fBpreserve.c\fP.
  1295. .Ex edit.c
  1296. Deals with insert and replace modes.
  1297. .Ex normal.c
  1298. Handles normal-mode commands.
  1299. .Ex map.c
  1300. This file is responsible for all input mapping (both set up by the
  1301. \fB:map\fP command and internally for function-key mappings;
  1302. it also implements a stuff-characters-into-the-input-stream
  1303. function for use within the editor.
  1304. This is used, for example, to implement command redo
  1305. (but \fInot\fP to implement \*Qundo\*U and \*Qput\*U as in STEVIE).
  1306. .\"-----------------------------------------------------------------
  1307. .sp
  1308. .LP
  1309. Colon (\fBex\fP-type) commands are handled by this group:
  1310. .Ex cmdline.c
  1311. Decodes and executes colon commands.
  1312. .Ex ex_cmds1.c
  1313. File-, \fBBuffer\fP- and \fBXviwin\fP-related colon commands.
  1314. .Ex ex_cmds2.c
  1315. Other colon commands (e.g. shell escape).
  1316. .\"-----------------------------------------------------------------
  1317. .sp
  1318. .LP
  1319. Screen updating is done within the following files:
  1320. .Ex screen.c
  1321. Screen updating code, including handling of line-based entry
  1322. (for colon commands, searches etc) as they are typed in,
  1323. and display-mode stuff (for parameter displaying,
  1324. .B :g/re/p
  1325. etc).
  1326. .Ex cursor.c
  1327. This file contains the single function \fBcursupdate()\fP,
  1328. which is responsible for deciding where the physical screen cursor
  1329. should be, according to the position of the logical cursor in the
  1330. buffer and the position of the window onto that buffer.
  1331. This routine is not very optimal, and will probably disappear in due course.
  1332. .Ex defscr.c
  1333. This file contains the default implementation of the \fBVirtScr\fP class,
  1334. on top of the old terminal/system interface.
  1335. .Ex status.c
  1336. Functions to update the status line of a window; there are different
  1337. functions to display file information (name, position etc.)
  1338. and error/information messages.
  1339. .\"-----------------------------------------------------------------
  1340. .sp
  1341. .LP
  1342. These files deal with specific areas of functionality:
  1343. .Ex find.c
  1344. Search functions: all kinds of searches, including character-based
  1345. and word-based commands, sections, paragraphs, and the interface to
  1346. \*Qreal\*U searching (which is actually done in
  1347. .B search.c ).
  1348. .Ex mark.c
  1349. Provides primitives to record marks within a \fBBuffer\fP,
  1350. and to find the marks again.
  1351. .Ex mouse.c
  1352. Code to handle mice moving the cursor around and resizing windows.
  1353. .Ex param.[ch]
  1354. Code to handle setting of, and access to, parameters.
  1355. (These are things like \fBtabstops\fP, \fBautoindent\fP, etc.)
  1356. .Ex pipe.c
  1357. Handles piping through system commands.
  1358. .Ex preserve.c
  1359. File preservation routines.
  1360. .Ex search.c
  1361. Code for pattern-searching in a buffer, and for substitutions
  1362. and global execution.
  1363. Uses \fBregexp.[ch]\fP for the actual regular expression stuff.
  1364. .Ex tags.c
  1365. Routines to handle tags \(em for \fB:tag\fP, \fB-t\fP and \fB^]\fP.
  1366. .Ex undo.c
  1367. Code to deal with doing and undoing; i.e. making and unmaking
  1368. changes to a buffer.
  1369. This is one of the more complex and delicate files.
  1370. .Ex yankput.c
  1371. Code to deal with yanking and putting text, including named buffers.
  1372. .\"-----------------------------------------------------------------
  1373. .sp
  1374. .LP
  1375. while these files provide lower-level functions:
  1376. .Ex alloc.c
  1377. Memory allocation routines.
  1378. .Ex ascii.[ch]
  1379. Deals with the visual representation of special
  1380. characters on the display (e.g. tabs, control chars).
  1381. .Ex buffers.c
  1382. Routines dealing with the allocation and freeing of \fBBuffers\fP.
  1383. .Ex fileio.c
  1384. File I/O routines; reading, writing, re-editing files.
  1385. Also handling of the \fBformat\fP parameter.
  1386. .Ex flexbuf.c
  1387. Flexible-length character-buffer routines.
  1388. .Ex misccmds.c
  1389. Miscellaneous functions.
  1390. .Ex movement.c
  1391. Code to deal with moving the cursor around in the buffer,
  1392. and scrolling the screen etc.
  1393. .Ex ptrfunc.[ch]
  1394. Primitives to handle \fBPosn\fP structures; including various
  1395. operators to compare positions in a text buffer.
  1396. .Ex "regexp.[ch], regmagic.h"
  1397. Regular-expression stuff, originally written by Henry Spencer
  1398. (thanks Henry) and slightly hacked for use within \fBxvi\fP.
  1399. .Ex signal.c
  1400. Handling of terminal-generated signals in an ANSI environment.
  1401. .Ex virtscr.h
  1402. Virtual Screen interface definition.
  1403. This is a new part of \fBxvi\fP, and is not yet fully completed.
  1404. When it is finished, it will provide the ability to implement
  1405. \*Qnative\*U versions of \fBxvi\fP under various windowing systems,
  1406. in a clean and wholesome way.
  1407. Currently there is a single instance of the \fBVirtScr\fP class, which
  1408. is defined on top of the old system/terminal interface.
  1409. .Ex windows.c
  1410. Code to deal with creating, deleting, resizing windows.
  1411. .Ex version.c
  1412. Contains only the version string.
  1413. .\"-----------------------------------------------------------------
  1414.